Code Conventions
Refer to this page in order to verify that all written code conforms to the standards agreed upon by the team. Most conventions are already agreed upon as a result of shared education standards, but some others have been defined after referral to the C# Coding Conventions, as this is the language that the project is expected to be mostly composed of. File Organisation Never declare more than one class per file. Layout and Ordering The layout of a file is to follow the following standard order: #Comment block at the beginning, that identifies the name of the file, the latest author/editor, the latest editing date and any notes that may be needed #All statements that call for importing of external libraries or classes. #Namespace definition (if necessary). #Class definition #Variables of class #Initialisers of class #Methods of class #Main method of class (if applicable). Naming Conventions General rules Use names that are understandable and describe the purpose, don't shorten in order to save space / time. Avoid using numeric values in variable names. Variables Naming of variables is dependent on their type and pronouncement. All variables must be solely composed of alphabetic letters and/or underscores. All characters of a variable name must be a lower-case letter or underscore, unless the character is being used to represent the commencement of a new word within a variable (except for the first word / character). Furthermore, no variable name may start with an underscore. Variables will use lowercase camelCase. Example: var newVariable; If a variable is of type const, the name must be in all upper-case, underscores are required to identify words. Example: ''const int TOTAL_VALUES; Functions All characters of a functon name must be a lower-case letter or underscore, unless the character is being used to represent the commencement of a new word within a variable. Furthermore, no variable name may start with an underscore. Example: public void DoSomething() {} Commenting Comments to describe a block must be place above the block only. Comments describing the purpose of singular statements must be written to the right of the statement. Use /* */ comment tags for comments that span multiple lines (rather than using // for each line). Formatting Statement Layout Do not write multiple statements on a single line. Aim for simplification of function size, avoid exceeding 45 lines in a single method where possible. Add a single space around each comma and operator Indentation All indentation is to be done with the tab key. Use indentation as a means to describe code dependency on a previous condition taking place. The use of indents should signify that the scope of a statement is shared by other statements that share the same level of scope within the same boundaries between lesser-indented lines. It is up to the team member whether they would prefer to use the '{' value, which normally follows conditional statements, at the end of the statement or on a new line by itself. The closing bracket '}' must always be on it's own line at the end of a block, unless it is completing a do-while block. If there are comments appearing on 3 or more consecutive lines, try to arrange them so that they are in line with each other (by using the tab key). Conditional Blocks As per the required syntax, all blocks of code are to be written within {} brackets. However, if only a single statement follows from a conditional statement, the team member may elect to omit the {} brackets and their formatting rules (however, they must remember to indent the statement) ''Example: if (number > 5) computeValue(number); Example of formatting: /// Filename: example.cs /// Latest edit by: acf502 /// Edit date: 1/5/14 /// Notes: This is just an example. using System; namespace TestExample { class Hello { // member variables int value; static void Main(string[] args) { value = 1; Console.WriteLine("Value: {0}", value); } } } Documentation All code should follow the XML commenting scheme , as described by Microsoft. Following these rules, it will be possible to build complete sets of documentation, with instant formatting, through use of the VSDocMan extension in Visual Studio 2012. By following such processes, we will be able to streamline the documentation generation process by producing formatted HTML documents VSDocMan Procedure: #Download and Install trial version from either Visual Studio Gallery or from the VSDocMan site. #Open VSDocMan in Visual Studio 2012 #If VSDocMan is already congifure, select Compile -> Compile Project to output documentation of project. #Ensure that VSDocMan is configured to include documentation for all appropriate content. Check Code Members -> Member Types. Also check Output -> Syntax and Source Code to make sure that ", put a 'yes' or a 'no' between tags in a single line, e.g: /// yes). Category:System Implementation